Summary

Creates a central navigation hub for object storage documentation, addressing the scattered documentation problem identified in cohesion review.

Problem

From cohesion review (COHESION-REVIEW.md Issue #8, Medium Priority):

• Object storage documentation scattered across 4-5 documents:
  • explanation/data-pipelines.md (conceptual OAS intro)
  • how-to/use-object-storage.md (task-oriented)
  • how-to/configure-storage.md (configuration)
  • how-to/use-npy-codec.md (specific codec)
  • reference/specs/type-system.md (technical spec)
  • reference/specs/object-store-configuration.md (detailed spec)
• User trying to "add object storage" must consult multiple docs
• No clear entry point or navigation guide

Solution

New comprehensive index: how-to/object-storage-overview.md (400+ lines)

Content Structure

1. Quick Navigation by Task (Time-Saving Table)

2. Conceptual Understanding

• Why OAS exists (relational + object limitations)
• How OAS unifies both worlds
• Link to full conceptual doc

3. Three Storage Modes
Detailed comparison:

• In-Table (<blob>) - Fast, transactional, < 1 MB
• Integrated (<blob@>, <npy@>, <object@>) - Managed, deduplicated, > 1 MB
• Filepath (<filepath@>) - User-managed references

Each mode includes:

• What it is
• When to use
• Why choose it
• Code examples
• Guide links

4. Documentation by Level
Progressive learning path:

• Getting Started (3 guides)
• Intermediate (3 guides)
• Advanced (1 guide)

5. Technical Reference
Organized links to:

• 4 specifications (technical details)
• 3 explanations (conceptual understanding)

6. Common Workflows
Real-world scenarios with step-by-step:

1. Adding object storage to existing pipeline (30-60 min)
2. Migrating in-table to object store (1-2 hours)
3. Working with very large arrays (setup guidance)
4. Building custom domain types (2-4 hours)

7. Decision Trees
Two flowcharts:

• Which storage mode? (in-table vs integrated vs filepath)
• Which codec for object storage? (npy vs object vs blob)

8. Troubleshooting Table
6 common issues with:

• Problem description
• Likely cause
• Solution guide link

Navigation Improvement

Before (Scattered)

User flow for "add object storage":

1. Search docs → find use-object-storage.md
2. Realize need store config → find configure-storage.md
3. Confused about codec choice → search more
4. Find type-system.md spec → too technical
5. Eventually piece together solution (30-45 min)

After (Guided)

User flow with index:

1. Go to Object Storage Overview
2. See "Quick Navigation" table
3. Click relevant task links in order
4. Complete task (10-15 min)

User Impact

Single entry point: All object storage docs accessible from one page

Task-oriented: Find what you need by what you're trying to do

Progressive learning: Clear path from beginner to advanced

Time estimates: Users can plan their time

Workflow-based: Real scenarios, not just API reference

Reduces friction: 4-5x faster to find relevant documentation

Cross-References

The index connects to:

• 7 how-to guides
• 4 specifications
• 3 explanations
• 2 tutorials

Placement

Added to how-to/index.md as first item under Object Storage:

## Object Storage
- [Object Storage Overview](object-storage-overview.md) ← NEW (navigation hub)
- [Use Object Storage](use-object-storage.md)
- [Create Custom Codecs](create-custom-codec.md)
- [Manage Large Data](manage-large-data.md)
- [Clean Up External Storage](garbage-collection.md)

Rationale: Overview comes first - users need navigation before diving into specifics.

Related

• Addresses COHESION-REVIEW.md Issue Broken glossary link #8 (Medium Priority)
• Complements storage decision guide (PR Add comprehensive storage codec decision guide #114) - index links to decision guide
• Works with specs index (PR Enhance specs index with reading order and cross-references #115) - index links to technical specs
• Part of comprehensive navigation improvement series